Create

Prepares to link a program to the KINGSTAR Subsystem.

Syntax

KsError Create(
     int Instance,
     int IdealProcessor
);

Parameters

Instance: selects which KINGSTAR Runtime instance you want to use when you have Multiple Master Package. If you don't have the package, set it to zero (0); if you have the package, the valid instance should be: 0 <= instance <= 63. The instance can be set according to your needs, for example: if you have three instances and want to use the third one, set it to two (2).

IdealProcessor: configures which core the KINGSTAR Subsystem runs on. All threads of the Subsystem run on the given processor. Core Zero is always for Windows. Other cores can be assigned to the Subsystem depending on your settings. By default, IdealProcessor is set to zero, meaning KINGSTAR will use the ideal processor configured in the instance configuration table (Control Panel > Runtime Settings > General Settings). If the table lacks settings for the given instance, the Subsystem may run on any core available to RTX64. If you set it to another number, such as two, the Subsystem will take the Core Two.

Return value

If the function succeeds, it returns errNoError, otherwise an error code. For more information about the error code, see the KsError list.

Remarks

This function should always be called first. All other functions will return errWrongEnvironment if Create has not been called.
Multiple instances means you have multiple ksRuntime.rtss running at the same time and controlling different network cards. If you have Multiple Master Package, you can use several Create to create multiple instances. For example, you have three Create functions. They can use the instance zero, one, and two for each of them. If you don't have Multiple Master Package, you can use several Create to create only one instance, which is the instance zero. Several applications can link to one KINGSTAR Runtime, but one application can't link to several Runtimes.
One KINGSTAR Runtime = One ksRuntime.rtss.

Example

Copy

//////////////////////////////////////////////////////////////////
//
// This code snippet demonstrates a basic flow of how to link to
// KINGSTAR subsystem and use the APIs to configure subsystem and
// control the EtherCAT network and motion devices.
//
//////////////////////////////////////////////////////////////////

KsError nRet = errNoError;
KsCommandStatus Command = { 0 };
SubsystemStatus Subsystem = { ecatOffline, ecatOffline, 0, 0, 0, {ecatOffline}, {ecatOffline}, {axisOffline} };

// Link to the KINGSTAR subsystem.
// If the KINGSTAR subsystem does not exist, it would create a new KINGSTAR subsystem.
// You have to call this API first before you use other KINGSTAR functions.
nRet = Create(0, 0);

// Check if the subsystem is started.
// A new KINGSTAR subsystem is not started by default.
nRet = GetStatus(&Subsystem, NULL);
if (Subsystem.State == ecatOP)
{
    RtPrintf("Subsystem already started: %x\n", nRet);
}
else if (nRet == errNoError && Subsystem.State == ecatOffline)
{
    // When the subsystem state is ecatOffline, you can use below APIs to configure settings:
    //
    // Subsystem Configuration APIs
    // Axis Variable APIs
    // AddModuleConfiguration()
    // RemoveModuleConfiguration()
    // SetConfigurationAxseCount()
    // SetConfigurationIoCount()
    //
    // If you just want to use the default setting, skip this part and start the subsystem.

    // Start the subsystem. It would change the subsystem state to ecatOP.
    // This function is asynchronous so the network is not started yet when it returns.
    // Use WaitForCommand() for synchronization.
    Command = WaitForCommand(30, TRUE, Start());
}

// Now the subsystem state is ecatOP, you can use below APIs to control the subsystem and devices:
//
// Subsystem Control
// Slave Control
// Axis Control
// IO Control
// Heartbeat
// COM API
// Motion API
//
// You can also change the subsystem state or slave state.
// Please check "Usable EtherCAT states" section and the API pages to find out
// which functions you can use in different states.

// Stop the EtherCAT network before destroying KINGSTAR Subsystem or before re-configuration.
Command = WaitForCommand(5, FALSE, Stop());
if (Command.Error)
{
    RtPrintf("Stop Failed: %d\n", Command.ErrorId);
}

// Terminates the KINGSTAR Subsystem if there is no other application connected to it.
nRet = Destroy();
if (nRet != errNoError)
{
    RtPrintf("Destroy Failed: %x\n", nRet);
}

Requirements

	RT	Win32
Minimum supported version	4.0	4.0
Header	ksapi.h	ksapi.h
Library	KsApi_Rtss.lib	KsApi.lib